by Br'fin (Jeremy Parsons), Dan Johnson, and Lurker (Evan Harper)
Pfhred has been created to edit the contents of a Marathon Shapes File.
Rather useful for those times when just modifying a physics model isn't enough to bring your worst fears to life, now you can add them yourself!
How do you use it? Simple enough.
Menu Bar
File Menu
Open - Brings up a file dialog so you can open a shapes file and be presented with it's File window.
Close - Closes the front most window.
Save - Saves any changes into the current shapes file.
Revert - Disposes of any changes to the shapes file since the last save.
Quit - Quits Pfhred and returns you to wherever.
Save As does not work.
Edit Menu
Cut - Cuts text to the clipboard.
Copy - Copies the currently selected text or picture to the clipboard.
Paste - Pastes text or a picture into the currently visible window.
Paste into New Wall - Pastes a picture into a new wall instead of replacing an existing wall image. (This is how you add walls)
Clear - Clears selected text
Color… - Brings up a dialog to edit the cluts of the current collection.
Add New HLS - Creates a new High Level Shape. This is how you can create a new animation for a creature without replacing an existing one.
Delete HLS - Deletes the selected High Level Shape, saving space in the shapes file.
NOTE: This does not dispose of the bitmaps involved in that HLS. And deleting bitmaps is too hairy to implement at the current time. If you really want to completely get rid of a bitmap instead of replacing it to save space, then try replacing the bitmap with a very small (IE 3x3) bitmap.
Undo does not work.
Option Menu (was View Menu)
Background Color… - Brings up the Color Picker by which to choose the background color used behind the displayed images. By using the same color in a picture that you're pasting in, then anywhere that color appears in your picture is treated as see through when shown in Marathon itself.
Show Origin - Toggles whether or not the Origin of an animated picture is shown. While visible it is possible to drag the origin to a new location. Typically the center of a shot, or the spot where the object touches the floor. The Origin is displayed as a blue dot on the picture
Show Key Point - Toggles whether or not the Key Point of an animated picture is shown. See Special Considerations below. While visible it is possible to drag the Key Point to a new location. The Key Point is displayed as a red dot on the picture.
Animation with Sound - Toggles whether or not Pfhred tries to play the sounds associated with the given HLS when you animate the shape either forwards or backwards. If you have
not already selected the Marathon Sound file it will prompt you.
File Window
The heart of the shapes file, each item listed in this window presents a complete self contained collection for a particular set of items, including the colors used and information for how to display them. Some examples are Fighters and Alien Walls. Double-clicking on one of these will bring up a window for that Collection.
NOTE: The File window now lists only the available collections and sorts them
Collection Window
The Collection Window presents a list of entries in the collection, as well as listing various stats about the information held within the collection. The Scale Factor shown here only has an affect for Objects. It has no effect on Interfaces and Walls.
If the Collection is for Interfaces and Walls, then by double-clicking on an entry from its list, you will bring up a Wall/Interface Window.
Walls are also displayed pictorially in the collection window.
If the Collection is for Objects, then it will present a list of existing High Level Shapes(HLS). Double-clicking on one of these will display a HLS Window.
Wall/Interface Window
There isn't much information to be shown for walls or interfaces. Just the image's height and width. There is also a popup menu which displays the current scaling factor (only affects viewing, not the saved shape)
Of course the wall/interface in question is also displayed. New images can be pasted in over these and will be forced to the rectangle of the image being replaced.
HLS Window
A High Level Shape is an organization for a specific animation, such as a Fighter running as seen from all directions. A description of its fields follow:
Type: This menu describes how many views an object has, and how many views Marathon actually loads. ie, an ANIMATED 8 means Marathon loads all 8 views. An ANIMATED 5 TO 8 means that Marathon loads the first 5 views, then extrapolates the other 3 by mirroring some of them.
Transfer Mode: Describes how Marathon should draw an object. See Special Considerations below.
Frames per View: How many frames of animation the object has.
Ticks per Frame: The number of 30ths of a second between one frame of animation and the next.
Key Frame: The key frame of an object. If this value is greater then 0 then this HLS can be used as an attacking shape for the creature. If used as an attacking shape, then the key frame is the frame of animation that Marathon syncs shots created by the creature to.
Period: The period used for any additional affects caused by the Transfer Mode.
This value is typically the number of frames * the interval between frames.
Scale Factor: If a scale value other then 0 is used here, then this scale value will override the scale value used for the collection as a whole.
First Frame Sound, Key Frame Sound, and Last Frame Sound:
If a sound has been selected, then the speaker icon will have sound waves and the Try button will be available.
Clicking on either the speaker or the Try button will play the currently selected sound for that frame.
Browse lets you look at and try all the possible sounds in the Marathon sounds file. You can then select one of these sounds to be the new sound for that frame. Browsing also is the only way to select a different Sound file.
Using any of these will prompt for a Marathon sounds file if one hasn't been selected yet.
Height: Height of the current image
Width: Width of the current image
View: Select the view of the current shape. This value isn't saved.
If the image is selected, then the left and right arrows will rotate the object left and right.
Frame: Select the current frame of animation of the shape. This value isn't saved.
Holding down the arrow will try to animate the given shape, attempting to apply the current interval. After cycling through all the frames, the animation better approximates the speed at which Marathon would cycle them.
If the image is selected, then the up and down arrows will also animate the object forwards and backwards.
Clut: Selects the current clut to show the image with. This value isn't saved.
If the image is selected, then pressing the number of the clut will change to that clut.
Scale: Popup to let you scale the displayed image. This value isn't saved.
Shape: The current Low Level Shape(LLS) for the selected view and frame.
Image: The image for the current LLS
X-Mirror: When checked, Marathon will display the image flipped. (Pfhred will display the image flipped as well)
Keypoint-Obscured: Only used for a Player's legs. When checked, Marathon should draw a Player's torso in front of the legs instead of behind.
Minimum Light Intensity: Ranging from 0-100%, at least how bright the shape is if in an area that is darker than this minimum. Used for things that cause bright light, such as creatures firing weapons and the energy bolts and explosions created.
Origin X, Y: The place where the base of the creature object is.
Key X, Y: Only used for a Player's legs. Tells Marathon where to place the origin of a Player's torso. ie, where to join the torso to the legs.
And of course the actual image itself.
After selecting the actual image, you can copy the picture out.
Color Editor
This is the dialog that appears when you select Color… from the Edit Menu.
It presents a display of all the colors in the current clut, as well as controls for editing them. If a color is framed by red, then it's not safe to use with Marathon in 256 color mode. The only exception to this is the colors of the Splash Graphics collection.
Clicking on a color selects it.
Double-clicking on a color brings up the Color Picker to select a new color to replace it with.
Shift-dragging on the colors will select a range of colors.
Clut: This menu provides a a way to switch between the cluts of the current collection.
Add Clut: Adds a clut to the end of the current cluts and copies all the colors of the current clut to it. Pfhred allows for up to 8 cluts on object collections, and only one on walls or interfaces.
Delete Clut: Removes the currently selected clut.
Insert: Adds a single color either to the end of the clut, or before the current selection.
Cut, Copy, Paste, Clear: Work like the same items normally found in the edit menu, and their keyboard equivalents will still work.
Blend: Creates a gradual change of colors between the first selected color and the last one.
Marathonify: Replaces the selected colors with their closest match from Marathon's original color table.
Load Clut, Save Clut: Loads or saves a clut. Loading a clut will try and preserve the other cluts of a collection as best it can within the new number of colors of the new clut.
The following formats can be loaded or saved:
Clut Resource: File type 'CLUT', clut resource 128. At least Superpaint used this kind of clut. Besides, it's easy to get to with ResEdit.
Photoshop Clut: A 256 color clut in Photoshop format, any blank spots are filled in with black. (Ok, ok, so that goes for the clut resource too)
Photoshop Swatch: A partial clut consisting only of the current colors. Any blank places aren't touched or recorded. I don't know if versions of Photoshop before 3.0 can read these though.
Special Considerations
Pasting
When pasting in a new picture, there are a few things to be considered.
Interfaces/Walls - Interfaces and walls are kept bound to the size of whatever picture you are replacing. This is because it would seem that Marathon would only expect those sizes, and does no scaling on them, or allow for placing them in any sort of new position.
New Interfaces cannot be added, there's no way, short of Bungie recoding Marathon, to use the new interfaces.
Walls can be added(instead of replaced) by selecting the Paste into New Wall command from the Edit Menu instead of Paste.
Objects - When a High Level Shape window is open, you can paste new images in for the animations. The new picture can be any size, and can be different from the old picture.
To determine what areas of the object are see through, use a paint program to set those areas to the same color as the background color you've selected through the Background Color… command from the View Menu. Also, the first three colors in the current clut are also treated as background colors, and Pfhred will render them transparent too.
To add a new picture (instead of replacing an existing one), set the Image field of the currently selected shape to -1 and then select Paste from the Edit Menu.
It is possible for a shape to be too complex for Marathon to render within the given image size. If this happens, Pfhred will alert you to the problem and abort the paste.
Transfer Modes
Marathon has a variety of effects it can apply to a given shape when displaying it.
Normal: The shape is drawn as is, while applying light and its own minimum light to it.
Invisibility: The shape is drawn as an obvious darkening of the area it's in, like how a player who's found one Invisibility power-up appears.
Subtle Invisibility: The shape is drawn as a very, very slight darkening of the area it's in, such as a player under the influence of two Invisibility power-ups.
Static: The object is completely covered with an assortment of shifting, colored, pixels.
50% Static: The object is covered with a see-through assortment of static. An example is a Compiler getting hit.
Fade Out Static: Over the course of the shape's Period the object goes from 100% static to 0% static. An example is the death of a Compiler.
Pulsating Static: Ok, I admit I don't quite know what this one is, but would love to know.
Fold In, Fold Out: The respective effects for a player teleporting in or out.
The remaining transfer modes appear to be for Polygons only, when used with objects they produce unpredictable switches between the object being rendered normally or with one of the other transfer modes. It is unknown as to how stable Marathon is with these.
Key Points and Key Frames
While they may look similar they affect two different aspects of how Marathon works with things.
Key Point: The Key Point is always associated with a Player's legs in the shapes file. It tells Marathon where to link a Player's torso to their legs.
If Keypoint-Obscured is checked, then the torso will be drawn in front of the legs instead of behind them.
Key X, Y are the coordinates of the Key Point. If Show Key Point is selected in the View Menu then the Key Point is drawn as a red dot on the picture, and can be dragged to a new location.
Key Frame: This is the frame that Marathon syncronizes attacks made with this shape to. That is, if the Key Frame is set to 3, then, upon reaching the 3rd frame of this animation, the Key Frame Sound will be played, and a shot will be created at a point indicated by the current Physics Model.
If the Key Frame for the shape is set to 0, then the shape cannot be used for the attacking animation. Or, rather, the creature will try to attack with this animation, but no shot will ever be created.
Color Editing
General notes
The way Marathon deals with colors is complex. For starters, the way it works in 256 colors and up is that in actuality no more then 256 colors are used in all of the shapes you see in the game. Honest, thousands of colors and millions of colors can do better shading. But the base Marathon clut is only 256 colors. And the clut included with Pfhred is the sum total of all those colors.
Editing the First Clut of an Object
The first clut of a collection(Clut 0) has special meaning to the game. Marathon uses this clut for optimizing the images internally with respect to the current clut. And for the subsequent cluts of the collection. The result is that changes to the first clut will look fine, but if one of the other cluts is used then the object will get weird white patches.
Things should be fine if you keep the following rules in mind:
• Never duplicate colors in Clut 0. These colors are framed with yellow.
• Keep colors in a range similar to each other in the first clut.
By range, I mean any group of colors that starts with some prominent color then ramps down to black. You see a lot of these in Marathon's own color tables. However, in the first clut, you cannot break up a color band that Marathon is expecting. That is, you can't have a range with alternating purple and green, even if they don't duplicate anything.
• Keep ranges similar between cluts of the same collection.
Marathon appears to use ranges to determine what color to go to from the current one as light decreases or increases. In order to avoid more glitched colors, make sure you have these areas the same length and in the same spots for all the cluts of a given shape.
Other color editing notes
Marathon, at least later versions, is capable of using any color found in a color table, even if it's not a 'Bungie approved' one on thousands of colors and up. But I highly recommended that you design your shapes to use just the colors found in the game, so even people who only have 256 colors can still them, if you plan to distribute the shapes.
To help you spot the 'bad' colors, Pfhred frames non-Marathon colors in red, and it frames duplicate colors with yellow.
One last note on this, a non-black color as the last color in a clut is also considered bad. And Marathonify will force it to black.
It's probably easier and looks better to copy a range of colors from another clut and paste it in rather then to use blend and Marathonify. ( I always find that to be the case for me anyways :) )
By the way, if someone were to be really enterprising and replace every instance of a color with a new one, then it would appear to be possible to safely use that new color on even 256 colors displays.
Please get back to me with any other things about color tables that you discover to be unusual or unexpected so that I can spread the word in future docs.
Sounds
Sounds can be linked to the animation of an object, that's why you can browse and select sounds through Pfhred. And they can be cued up to start on the first frame, the last frame or on the key frame. There isn't much to worry about here as long as you
use the original Marathon Sounds file. You should note that the sounds that have a number are variations. In the Sound file they are within 3 resource numbers of the first sound, and Marathon may play sound 2, 3, or 4 in place of 1 if you have selected one. So it is generally best to choose sound 1 of a series of variations.
Final Note
I'd advise you to find one of the shape moving programs, such as the Marathon Shape Shuttle, to make smaller files with only your changed shapes in them if you're planning on distrubuting your changed shapes.
So long and thanks for all the fish.
-Br'fin
Send all comments, bug reports, ideas, and grants to: brefin@cache.cow.net
Disclaimer
Br'fin and Pfhred are in no way connected to Bungie or its staff, and Bungie is not responsible for the actions and opinions of them.
Marathon is a registered trademark of Bungie Software Productions Corp.
You may distribute Pfhred as Freeware as long as all the original files are included.
If you want to include Pfhred as part of a commercial offering, please contact Br'fin (brefin@cache.cow.net) for permission, especially as he always has the most recent version.
